# -*- coding: utf-8 -*-
"""
Macana XML-RPC Dispatcher for Taíno
Copyright (C) 2009, Joshua "jag" Ginsberg <jag@flowtheory.net

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
"""

from taino.api import Interface

class IMacanaAuthentication(Interface):
    """IMacanaAuthentication
    
    This interface describes a way to authenticate a particular XML-RPC
    request as coming from a user in the auth system."""
    
    DEFAULT_FAULT_CODE = -32400
    UNAUTHORIZED_FAULT_CODE = -32401
    APPLICATION_FAULT_CODE = -32500
    METHOD_NOT_FOUND_FAULT_CODE = -32601
    INVALID_PARAMETERS_FAULT_CODE = -32602
    DISPATCHER_ERROR_FAULT_CODE = -32603

    def authenticate(request, method, method_args):
        """IMacanaAuthentication.authenticate:
        
        * request -- a django.http.HttpRequest object
        * method -- the XML-RPC method being invoked
        * method_args -- the arguments being provided to the XML-RPC method
        
        It is expected that implementations of this method will set the value
        of request.user appropriately to a django.contrib.auth.models.User or
        AnonymousUser -- it is then up the method itself to determine
        whether the user is authorized or not.
        
        Returns None.
        """

    def get_instructions():
        """Returns a Unicode string of instructions to a human user on how
        to interact with this authentication method."""

class IMacanaXMLRPCMethod(Interface):
    """IMacanaXMLRPCMethod
    
    This interface describes an XML-RPC method that the system's listener
    should accept and dispatch requests for."""
    
    def get_method_name():
        """Returns the name of the method implemented."""
    
    def get_arg_list():
        """Returns a list of XML-RPC argument types that the method expects."""
    
    def get_return_type():
        """Returns the XML-RPC type that this method returns."""
    
    def authorize(request):
        """Performs an authority test to determine whether a request is
        authorized. Returns a boolean -- True for authorized, False for
        unauthorized."""
        
    def handle_request(request, *args):
        """Executes the method for the given request on the given arguments.
        Returns a value convertable by xmlrpclib into the XML-RPC type of
        get_return_type()."""
